change31.txt
8/11/95
S. Weyer

Newt 3.1(N) & NewtPack 3.1(N)

- [note about version numbering, release schedule]
- NewtPack saves "small" packages on pre-1.3 ROM OMP (RUNewt no longer needed)
- NewtPack better progress feedback, faster, creates smaller packages
- NewtPack saves books, apps (autoClose option), autoparts (dispatch-only option)
- Heap button displays current heap/does gc; Eval Controls draggable off screen
- better coordination of Print&Notify behavior between Eval Log, Slurpee, NTK
  if you use Slurpee, you must use Slurpee 1.6 (earlier versions incompatible)
- uses DontAsk patch with standard keyboard (rather than custom keyboard)
- GetNamedResource works directly with Ben Gottlieb's Icon Editor
- internal cleanup, performance tuning, better heap use, additional preferences
- faster versions of Newt and NewtPack with native code available to registered users.


-----


- Version Numbering, Release Schedule

To help identify various versions (including beta, internal and native), I
have modified version numbering slightly.  The version number appears as part
of the About Box title in Newt, in the progress box for NewtPack, and the
title of Slurpee and Life. It will also appear in the filenames of the desktop
packages (shortened to "8.3" to make naming consistent across platforms;
app=4, version#=2, beta=1, Native=1 . pkg=3).

In addition to the main version number for public release,
e.g., "3.1" or "1.6", other modifiers may appear:
 "a" -- beta version indicated by lowercase letter (a-z)
 "D" -- Debugging info is included [you should not see]
 "P" -- Profiling is included [you should not see]
 "N" -- some Native code is included (usually a smaller, non-native version also avail)

(note: individual apps can add configuration info to this; for example,
NewtPack adds "+S" if "small" package saving method is being used)

For example, new releases:
  title             filename
  -------------     -----------
  Newt 3.1          Newt31.pkg
  NewtPack 3.1      Pack31.pkg
  NewtPack 3.1N     Pack31N.pkg
  Slurpee 1.6       Slrp16.pkg
  Slurpee 1.6N      Slrp16N.pkg
  Life 1.3N         Life13N.pkg

Historically, I have been making public releases of Newt and associated tools
about every three months, unless there is a "show stopper" bug.  Much more
frequently than this, and the overhead of updating all of the doc files,
testing, and uploading to all of the various services and formats becomes too
time-consuming.  As I fix bugs, add features and tune performance, I will
continue to release beta versions via my web/ftp site (I am also looking into
the NEWTVEN area on Compuserve); I can distribute versions via email for
users who have a particular need.  If you download a beta version, please let
me know if it works or doesn't work for you and email me comments; also,
continue to check periodically (every week or two) for newer versions.

I will be updating the manual to remove RUNewt stuff, incorporate the
information in this file and Q&A digests, and generally add to system
function and method descriptions (I had waited for NTK 1.5.1 documentation,
but there really wasn't anything new). I also want to check that the PDF I
create is more portable (several users had reported problems with fonts and
such). Due to several upcoming trips, I don't think this will be done until
late-September. In the meanwhile, the 3.0 manual will have to do, along with
this changes file.  I will also go thru the old DTS examples systematically
to modify according to the latest versions.


---------


- NewtPack saves "small" packages on pre-1.3 ROM OMP (RUNewt no longer needed)

On an OMP (pre-1.3 ROM Original Message Pad), you can save a package which is
somewhat larger than the remaining heap available after you have built your
app; practical limit for now is probably ~30-40K. For OMP, NewtPack creates
the package as a single object in heap. For other MPs, NewtPack normally uses
a buffered scheme to save 4K segments in a soup, thus allowing arbitrary size
packages; this "small" method may be a little faster (less soup access &
buffer thrashing), so if you'd like to try this on small packages (for OMP
it's automatic/required):
    :setPreference('smallPackage,true)

progressBox displays version 3.1+S -- "+S" indicates "small" method in use

RUNewt is no longer needed/distributed/supported.


-----


- NewtPack better progress feedback, faster, creates smaller packages

To give another indication of progress, the progress box shows the most recent
slot saved.  To speed saving, it omits displaying some "system" slots and
does not refresh the gauge quite as often.  (I had tried a version which
would display the entire path for arrays and frames, but these were generally
too long for the screen). When NewtPack finishes saving, it displays
"<Installing>" while the system installs the package. While saving, progress
box does not show a closebox. If an error occurs, a closebox (re)appears.

Instead of trying to calculate how large a package might be, Newt/NewtPack
defaults to 40000 for scaling the gauge.  If you have built your package
earlier and know the approximate size, you can put a sizeHint slot in your
_package frame and NewtPack will use this for the gauge's maximum value, e.g.,
  {_package:
     {sizeHint: 35000, 
     ...
     
After doing some profiling and recoding in NTK 1.5, the regular (totally
non-native version of NewtPack) saves somewhat (15-25%?) faster (smarter
sorting of slots in big frames, better handling of frame maps and symbols).

In case your app has any circular references in the template structure,
these will now be saved properly (it may be difficult to create these though
in Newt).


-----


- NewtPack saves books, apps (auto-close option), autoparts (dispatch-only option)

NewtPack can now save book types -- it is still tedious to create books (see
books.nwt), but at least they can be saved as packages. Some internal cleanup
so that NewtPack can be used directly by Newt's Cape (w/o Newt) [coming soon:
"Newt's Cape" -- an easier way to create books & forms]
  
Allows a package to set "autoClose" (default: nil). Normally, an app
automatically closes when another autoClose app opens. If you have a "floating tool",
you may not want this to happen, so
  _package: {autoClose: 'noAutoClose, // do not automatically close

Packages now contains two identical dates for create & modify (earlier they
were in different units due to a misunderstanding about format).

NewtPack can create "dispatch-only autoparts" -- these run only once when
initially installed; but are not saved so they do not run again after restart
or card insertion). [this has not been tested]
  _package: {dispatchOnly: true, // default for autopart is nil

see Mike Engber's bitparts article (ftp.apple.com/dts/newton/articles) for
when this might be useful

Fixes a bug that primarily affected building an autopart which already had an
existing package -- running out of heap (Newt tried "fixing" the old package
object which included the "store"). This should hopefully fix some other
problems related to removing packages.


-----


- Heap button displays current heap/does gc; Eval Controls draggable off screen

Tap button to start updating or to force a gc (garbage collect) note: this
updates only during system idle; it does not update during a build. You can
turn this on automatically and set the frequency via two preferences:
  :setPreference('autoHeap, true) // default=nil
  :setPreference('heapFreq, 5000)  // #msecs. default=15000 (every 15 seconds)
  
If you manually started it, you can stop it by just closing Eval Controls &
re-opening.

Eval Controls (like Slurpee) is draggable off right edge of screen. 
Lower left corner is a good place to grab.

Select All and Write() experimental commands added to action menu.  Select All
highlights all of the current text field, e.g., source editor, Eval field, or
Eval Log. This could be handy for dragging to another app via clipboard, or
use with Write(). The Write command uses the Write function on contents of
current text field or highlighted range -- typically printing text to Slurpee
or NTK Inspector (I used Write instead of Print since Newt's Print may
quoting inside symbols and strings). Write() could be useful for editing a
single field on the desktop (and then sending it back via Slurpee in Inspect?
mode). These features will probably evolve, along with a more official API
for having other tools talk to Newt and/or Slurpee.


-----


- better coordination of Print&Notify behavior between Eval Log, Slurpee, NTK
  if you use Slurpee, you must use Slurpee 1.6 (earlier versions incompatible)

Newt saves the global Print and Write functions and global Notify method, and
redefines these when it is open (or asked to by Slurpee).

when you Print or Write a value (directly via function or via Eval), result
goes to Eval Log (if Print? is on) result also goes to either Slurpee (if
connected) or to the original Print/Write function (NTK Inspector if
connected) so, you can see result in 0,1 or 2 places.

When you generate an error (directly via Notify or via bugs) error goes to
Eval Log (if Newt is open, regardless of Print? setting) error goes to
Slurpee (if connected) if Slurpee not connected (and Newt is closed), error
goes to original Notify (dialog box and/or NTK Inspector); if Newt is open,
error is just printed, e.g., to NTK Inspector. so, you can see errors in 1 or
2 places. Newt could always invoke the original Notify method, but the Notify
dialog doesn't really add any new information.

This should provide somewhat better error behavior if your application
generates an error during development. If you weren't using Slurpee, error
went to a Notify dialog; now it goes to Eval Log.  Newt cannot provide
information from the "exception frame" (e.g., name of undefined variable or
method) since it is not available by the time Notify is invoked. (For those
of you with the NTK Inspector, it "cheats" by dumping some information before
the Notify; unfortunately, it doesn't use Write or Print). Another approach
is to invoke a suspect method directly in Newt's Eval field rather than
through the normal event loop, e.g., myapp.mybutton:buttonClickScript(); this
allows Newt to set up a context to capture the error (with more information)
sooner.

Finally, Newt restores the original Print,Write & Notify definitions when it
quits (or if Slurpee disconnects when Newt isn't open).  If for some reason
you want to use the original definitions during development, you can Eval
:setInspector(nil,true) to restore them and bypass much of Newt's print and
error behavior. setInspector now returns a status that can be used, e.g., by
Slurpee, to restore original state for more predictable Print/Notify behavior
when switching between EvalLog, NTK Inspector, Slurpee.

inspterm.nwt updated to coordinate Print/Notify changes; included .doc file

printRefresh preference can be used to force Print to occur sooner for Eval Log.
currently, when Print? is on, results are not refreshed after each Print, but
at the end, e.g., after a build.  to force a refresh (for Eval Log) after each
Print expression, :setPreference('printRefresh,true) // default is nil


-----


- uses DontAsk patch with standard keyboard (rather than custom keyboard)

Eliminates Newt's built-in keyboard object (but kept icon). Includes DontAsk
autopart with Newt -- this eliminates "Do you want to add" prompt, and works
better with other utilities like KeyMan and Graffiti.  Since DontAsk
initially starts with standard keyboard behavior (it asks for prompts), you
can set an 'askWords preference in Newt to set this for you next time the
keyboard opens in Newt:    :setPreference('askWords, nil)

Note: there is a bug in the standard keyboard (separately from DontAsk). If
you have a prompt visible, and close the keyboard by tapping the kbd icon
rather than the close box, then when the keyboard re-opens, the prompt will
re-appear but overwrite the top row of keys. I have a possible patch for
this, but don't know if it would interfere with patches.

-----


- GetNamedResource works directly with Ben Gottlieb's Icon Editor

Slurpee examples create soups (such as Bitmaps) with a Symbol 'name field.
Icon Editor has a 'name field, but it's a String type. GetNamedResource
checks index specifications for type of 'name. Also fixes a bug related to
repeated saving of packages.
  
to get an icon you create with Icon Editor 1.1 (see URL on the releases page)
  :GetNamedResource("Icons:BenG","foo",'icon) // returns 'icon field

  :GetPICTasBits("Bitmaps","foo") // returns 'bitmap field


-----


- faster versions of Newt and NewtPack with native code available to registered users.

A native version of NewtPack (with several RISC methods) [NtPk31N.pkg] is
~15-20%  faster overall than non-native version, but about double in size.
There are a few methods in Newt that can be made native -- I have to
determine how significant/noticeable this is compared to size tradeoff.  I
will continue to experiment...

-----


- internal cleanup, performance tuning, better heap use, additional preferences

fixed bogus "duplicate name" problem.
(undocumented order of union soups may differ from GetStores()).

source soup entries accessed via fewer undocumented slots/functions
(generally, more cleanup here needs to be done; perhaps at the Newton
Developer Conference programming labs)

folderTab now displays correct folder (sometimes previous name remained) for
some reason, similar (length?) names remained, e.g., test2, test3 (Newt now
does an extra refresh; Notepad still has this bug)

When changing folders (or upon startup), Newt displays names of
objects/methods as it's checking.  (Slurpee appears initially ~32 pixels
from the top so that after starting Newt, these names are visible).

better heap behavior after quit (removes extraneous Newt view slots)

prevent accidental quit via preference 'closeConfirm
  'alwaysConfirm // always ask
  'editedConfirm // only ask if there's an unsaved edit
  nil // don't ask (default)
  e.g., :setPreference('closeConfirm,'editedConfirm)

additional customization for Newt itself, e.g., adding buttons to status bar,
or preference picker to Eval Controls. (see new example: newtcust.nwt)

scrolling more "standard" (and added support for eventual horizontal scrolling,
though still unclear whether Newton really supports this for text; see QA)

user apps and books :open more cleanly (less behind-the-scenes kludgery)

evaluation context/inheritance hierarchy modified
  previously:  root <- newt <- constants <- yourapp
  now:         root <- constants <- newt <- yourapp
  this provides the same development-time context to your app.  however, it
  makes app:open() simpler and allows addition of children to Newt
  itself via header syntax (see next).

Newt header syntax now allows use of "." and "+" on arbitrary frames. 
Previously, you could only add slots and children to children or prototypes
(whose name began with "proto"); otherwise, you probably saw an error message
about "run_method" not defined. You can now do this for any frame or user
proto (and Newt will splice in an inheritance context during development to
make it work).  So the following will now work:

  myApp.foo
  {a: nil,
  b: nil}
  -----
  myApp.foo.bar
  {aa: 1, bb: 2} // this used to break
  -----
  myApp.aproto
  {z: 3}
  -----
  myApp.aproto.somemethod
  func() nil // this used to break
  -----
  myApp.aproto+achild
  {...} // this used to break

A corollary to this is that some latent bugs in your application may be
revealed sooner, especially in apps that use protos as non-view classes
(e.g., InspecTerm), since Newt adds "fake" inheritance links only if needed.

fixes a few low heap conditions during check & build.
(hypothesis: the compile function doesn't do a gc if needed;
improvement: reduced # of separate source substrings/copies before compile)

removePackage can accept a "Newt symbol" (if app is built) in addition to an
appSymbol -- this is the same (more or less) as
    :removePackage(newtView.(sym).appSymbol)

    :removePackage('myApp)        // works if app is under development
    :removePackage('|myApp:Newt|) // works anytime (no confirm)
    :removePackage(nil) // select from menu of packages

RemovePackage now sorts packages alphabetically in popup

To support RemovePackage more efficiently, addApp now remembers if a package
already exists (and uses this in installApp, saveApp, removePackage)


removed Newt methods/slots:
  :Print -- use Print function
  :Write -- use Write function
  :addProtoDict -- use :DefConst or @literal for non-standard protos
  .protoDict (slot) -- ditto
  :addPackage -- use :addView
(note: there were some warnings in earlier release notes that these might
go away.)

installApp reports error if a package already exists. If you do a build to
create an application (in heap), but already have a package with the same
name (appSymbol), then when you do an :installApp(myApp,true), this could
interfere with the currently installed package (changing Extras icon,
redefining  change Extras icon, overwrite global state via installScript,
etc. So, Newt reports that package already exists.  At this point, you can do
removePackage yourself, e.g., :removePackage('myApp)

If you do :installApp(myApp,nil) directly [or the system calls it via
:removeApp or when Newt quits] and the package already exists, Newt does not
do the de-install and reports no error.  [This should fix the problem where a
package's icon might disappear from Extras (until you restarted)].

I noticed one occasion where Newt's icon disappeared when I ok-ed "Replace
Package?" -- the existing package was removed correctly, but the system
removed Newt from Extras (restarting fixed the problem). I think this is a
Newton system problem -- if anyone can reproduce, please let me know.


For emergency situations where you've run out of heap while trying to save
source, you should first close any other views you have open (Slurpee,
EvalLog, keyboards, other tools). If that isn't enough, you can Eval
:help_save().   This removes user-defined apps, methods & constants and
uncaches various Newt internal structures -- this could free up several K,
depending on number of sources etc. Hopefully, you can now save; quit (rather
than continuing to work) and then restart Newt (you may wish to reboot your
Newton first to maximize heap). (Eventually, this might also turn off syntax
checking so that a compile isn't necessary before saving source text).